home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / CrtPipelin.3 < prev    next >
Text File  |  1994-09-20  |  9KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_CreatePipeline(3)Tcl Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_CreatePipeline - create one  or  more  child  processes,
  12.      with I/O redirection
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      int
  18.      Tcl_CreatePipeline(_i_n_t_e_r_p, _a_r_g_c, _a_r_g_v, _p_i_d_A_r_r_a_y_P_t_r, _i_n_P_i_p_e_P_t_r, _o_u_t_P_i_p_e_P_t_r, _e_r_r_F_i_l_e_P_t_r)
  19.  
  20. ARGUMENTS
  21.      Tcl_Interp   *_i_n_t_e_r_p         (in)      Interpreter  to   use
  22.                                             for error reporting.
  23.  
  24.      int          _a_r_g_c            (in)      Number of strings  in
  25.                                             _a_r_g_v array.
  26.  
  27.      char         **_a_r_g_v          (in)      Array   of    strings
  28.                                             describing command(s)
  29.                                             and I/O redirection.
  30.  
  31.      int          **_p_i_d_A_r_r_a_y_P_t_r   (out)     The value at  *_p_i_d_A_r_-
  32.                                             _r_a_y_P_t_r is modified to
  33.                                             hold a pointer to  an
  34.                                             array    of   process
  35.                                             identifiers.      The
  36.                                             array  is dynamically
  37.                                             allocated and must be
  38.                                             freed by the caller.
  39.  
  40.      int          *_i_n_P_i_p_e_P_t_r      (out)     If this  argument  is
  41.                                             NULL   then  standard
  42.                                             input for  the  first
  43.                                             command  in the pipe-
  44.                                             line comes  from  the
  45.                                             current      standard
  46.                                             input.  If  _i_n_P_i_p_e_P_t_r
  47.                                             is   not   NULL  then
  48.                                             Tcl_CreatePipeline
  49.                                             will  create  a pipe,
  50.                                             arrange for it to  be
  51.                                             used   for   standard
  52.                                             input  to  the  first
  53.                                             command,  and store a
  54.                                             file id  for  writing
  55.                                             to   that   pipe   at
  56.                                             *_i_n_P_i_p_e_P_t_r.   If  the
  57.                                             command specified its
  58.                                             own    input    using
  59.                                             redirection,  then no
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_CreatePipeline(3)Tcl Library Procedures
  71.  
  72.  
  73.  
  74.                                             pipe is  created  and
  75.                                             -1   is   stored   at
  76.                                             *_i_n_P_i_p_e_P_t_r.
  77.  
  78.      int          *_o_u_t_P_i_p_e_P_t_r     (out)     If this  argument  is
  79.                                             NULL   then  standard
  80.                                             output for  the  last
  81.                                             command  in the pipe-
  82.                                             line  goes   to   the
  83.                                             current standard out-
  84.                                             put.   If  _o_u_t_P_i_p_e_P_t_r
  85.                                             is   not   NULL  then
  86.                                             Tcl_CreatePipeline
  87.                                             will  create  a pipe,
  88.                                             arrange for it to  be
  89.                                             used   for   standard
  90.                                             output from the  last
  91.                                             command,  and store a
  92.                                             file id  for  reading
  93.                                             from   that  pipe  at
  94.                                             *_o_u_t_P_i_p_e_P_t_r.  If  the
  95.                                             command specified its
  96.                                             own   output    using
  97.                                             redirection  then  no
  98.                                             pipe is  created  and
  99.                                             -1 is stored at *_o_u_t_-
  100.                                             _P_i_p_e_P_t_r.
  101.  
  102.      int          *_e_r_r_F_i_l_e_P_t_r     (out)     If this  argument  is
  103.                                             NULL  then error out-
  104.                                             put for all the  com-
  105.                                             mands in the pipeline
  106.                                             will   go   to    the
  107.                                             current      standard
  108.                                             error    file.     If
  109.                                             _e_r_r_F_i_l_e_P_t_r   is   not
  110.                                             NULL,  error   output
  111.                                             from all the commands
  112.                                             in the pipeline  will
  113.                                             go   to  a  temporary
  114.                                             file    created    by
  115.                                             Tcl_CreatePipeline.
  116.                                             A  file  id  to  read
  117.                                             from  that  file will
  118.                                             be     stored      at
  119.                                             *_e_r_r_F_i_l_e_P_t_r.      The
  120.                                             file   will   already
  121.                                             have been removed, so
  122.                                             closing   the    file
  123.                                             descriptor         at
  124.                                             *_e_r_r_F_i_l_e_P_t_r      will
  125.                                             cause  the file to be
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_CreatePipeline(3)Tcl Library Procedures
  137.  
  138.  
  139.  
  140.                                             flushed completely.
  141. _________________________________________________________________
  142.  
  143.  
  144. DESCRIPTION
  145.      Tcl_CreatePipeline processes the _a_r_g_v array and sets up  one
  146.      or   more  child  processes  in  a  pipeline  configuration.
  147.      Tcl_CreatePipeline handles pipes specified with ``|'', input
  148.      redirection  specified  with  ``<''  or  ``<<'',  and output
  149.      redirection specified with ``>'';  see the documentation for
  150.      the  exec  command for details on these specifications.  The
  151.      return value from  Tcl_CreatePipeline  is  a  count  of  the
  152.      number  of child processes created;  the process identifiers
  153.      for those processes are stored in a _m_a_l_l_o_c-ed  array  and  a
  154.      pointer  to that array is stored at *_p_i_d_A_r_r_a_y_P_t_r.  It is the
  155.      caller's responsibility to free the array when finished with
  156.      it.
  157.  
  158.      If the _i_n_P_i_p_e_P_t_r, _o_u_t_P_i_p_e_P_t_r, and _e_r_r_F_i_l_e_P_t_r  arguments  are
  159.      NULL  then  the  pipeline's standard input, standard output,
  160.      and standard error are taken from the corresponding  streams
  161.      of  the process.  Non-NULL values may be specified for these
  162.      arguments to use pipes for standard input and standard  out-
  163.      put  and a file for standard error.  Tcl_CreatePipeline will
  164.      create the requested pipes or file and return file  identif-
  165.      iers  that  may  be  used  to read or write them.  It is the
  166.      caller's responsibility to close all  of  these  files  when
  167.      they  are  no  longer needed.  If _a_r_g_v specifies redirection
  168.      for standard input or standard output, then pipes  will  not
  169.      be created even if requested by the _i_n_P_i_p_e_P_t_r and _o_u_t_P_i_p_e_P_t_r
  170.      arguments.
  171.  
  172.      If an error occurs  in  Tcl_CreatePipeline  (e.g.  ``|''  or
  173.      ``<''  was  the last argument in _a_r_g_v, or it wasn't possible
  174.      to fork off a child), then -1 is returned and _i_n_t_e_r_p->_r_e_s_u_l_t
  175.      is set to an error message.
  176.  
  177.  
  178. SEE ALSO
  179.      Tcl_DetachPids, Tcl_ReapDetachedProcs
  180.  
  181.  
  182. KEYWORDS
  183.      background, child, detach, fork, process, status, wait
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.